<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Getting started with Watcher | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="xpack-alerting.html" title="Alerting on cluster and index events">
<link rel="prev" href="xpack-alerting.html" title="Alerting on cluster and index events">
<link rel="next" href="how-watcher-works.html" title="How Watcher works">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="xpack-alerting.html">Alerting on cluster and index events</a></span>
»
<span class="breadcrumb-node">Getting started with Watcher</span>
</div>
<div class="navheader">
<span class="prev">
<a href="xpack-alerting.html">« Alerting on cluster and index events</a>
</span>
<span class="next">
<a href="how-watcher-works.html">How Watcher works »</a>
</span>
</div>
<div class="chapter xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="watcher-getting-started"></a>Getting started with Watcher<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/watcher/getting-started.asciidoc">edit</a><a class="xpack_tag" href="/subscriptions"></a>
</h2>
</div></div></div>
<div class="tip admon">
<div class="icon"></div>
<div class="admon_content">
<p>To complete these steps, you must obtain a license that includes the
alerting features. For more information about Elastic license levels, see
<a href="/subscriptions" class="ulink" target="_top">https://www.elastic.co/subscriptions</a> and
<a href="/guide/en/kibana/7.7/managing-licenses.html" class="ulink" target="_top">License management</a>.</p>
</div>
</div>
<p><a id="watch-log-data"></a>To set up a watch to start sending alerts:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<a class="xref" href="watcher-getting-started.html#log-add-input" title="Schedule the watch and define an input">Schedule the watch and define an input</a>.
</li>
<li class="listitem">
<a class="xref" href="watcher-getting-started.html#log-add-condition" title="Add a condition">Add a condition</a> that checks to see if an alert
needs to be sent.
</li>
<li class="listitem">
<a class="xref" href="watcher-getting-started.html#log-take-action" title="Configure an action">Configure an action</a> to send an alert when the
condition is met.
</li>
</ul>
</div>
<h3>
<a id="log-add-input"></a>Schedule the watch and define an input<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/watcher/getting-started.asciidoc">edit</a>
</h3>
<p>A watch <a class="xref" href="trigger-schedule.html" title="Schedule trigger">schedule</a> controls how often a watch is triggered.
The watch <a class="xref" href="input.html" title="Inputs">input</a> gets the data that you want to evaluate.</p>
<p>To periodically search log data and load the results into the
watch, you could use an <a class="xref" href="trigger-schedule.html#schedule-interval" title="Interval schedule">interval</a> schedule and a
<a class="xref" href="input-search.html" title="Search input">search</a> input. For example, the following Watch searches
the <code class="literal">logs</code> index for errors every 10 seconds:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT _watcher/watch/log_error_watch
{
  "trigger" : {
    "schedule" : { "interval" : "10s" } <a id="CO505-1"></a><i class="conum" data-value="1"></i>
  },
  "input" : {
    "search" : {
      "request" : {
        "indices" : [ "logs" ],
        "body" : {
          "query" : {
            "match" : { "message": "error" }
          }
        }
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1272.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO505-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Schedules are typically configured to run less frequently. This example sets
the interval to 10 seconds so you can easily see the watches being triggered.
Since this watch runs so frequently, don’t forget to <a class="xref" href="watcher-getting-started.html#log-delete" title="Delete the Watch">delete the watch</a>
when you’re done experimenting.</p>
</td>
</tr>
</table>
</div>
<p>If you check the watch history you’ll see that the watch is being triggered every
10 seconds. However, the search isn’t returning any results so nothing is loaded
into the watch payload.</p>
<p>For example, the following request retrieves the last ten watch executions (watch
records) from the watch history:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET .watcher-history*/_search?pretty
{
  "sort" : [
    { "result.execution_time" : "desc" }
  ]
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1273.console"></div>
<h3>
<a id="log-add-condition"></a>Add a condition<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/watcher/getting-started.asciidoc">edit</a>
</h3>
<p>A <a class="xref" href="condition.html" title="Conditions">condition</a> evaluates the data you’ve loaded into the watch and
determines if any action is required. Now that you’ve loaded log errors into
the watch, you can define a condition that checks to see if any errors were
found.</p>
<p>For example, the following compare condition simply checks to see if the
search input returned any hits.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT _watcher/watch/log_error_watch
{
  "trigger" : { "schedule" : { "interval" : "10s" }},
  "input" : {
    "search" : {
      "request" : {
        "indices" : [ "logs" ],
        "body" : {
          "query" : {
            "match" : { "message": "error" }
          }
        }
      }
    }
  },
  "condition" : {
    "compare" : { "ctx.payload.hits.total.value" : { "gt" : 0 }} <a id="CO506-1"></a><i class="conum" data-value="1"></i>
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1274.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO506-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The <a class="xref" href="condition-compare.html" title="Compare condition">compare</a> condition lets you easily compare against
values in the execution context.</p>
</td>
</tr>
</table>
</div>
<p>For this compare condition to evaluate to <code class="literal">true</code>, you need to add an event
to the <code class="literal">logs</code> index that contains an error. For example, the following request
adds a 404 error to the <code class="literal">logs</code> index:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST logs/event
{
    "timestamp" : "2015-05-17T18:12:07.613Z",
    "request" : "GET index.html",
    "status_code" : 404,
    "message" : "Error: File not found"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1275.console"></div>
<p>Once you add this event, the next time the watch executes its condition will
evaluate to <code class="literal">true</code>. The condition result is recorded as part of the
<code class="literal">watch_record</code> each time the watch executes, so you can verify whether or
not the condition was met by searching the watch history:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET .watcher-history*/_search?pretty
{
  "query" : {
    "bool" : {
      "must" : [
        { "match" : { "result.condition.met" : true }},
        { "range" : { "result.execution_time" : { "from" : "now-10s" }}}
      ]
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1276.console"></div>
<h3>
<a id="log-take-action"></a>Configure an action<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/watcher/getting-started.asciidoc">edit</a>
</h3>
<p>Recording watch records in the watch history is nice, but the real power of
Watcher is being able to do something when the watch condition is met. A
watch’s <a class="xref" href="actions.html" title="Actions">actions</a> define what to do when the watch condition
evaluates to <code class="literal">true</code>. You can send emails, call third-party webhooks, write
documents to an Elasticsearch index, or log messages to the standard
Elasticsearch log files.</p>
<p>For example, the following action writes a message to the Elasticsearch
log when an error is detected.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT _watcher/watch/log_error_watch
{
  "trigger" : { "schedule" : { "interval" : "10s" }},
  "input" : {
    "search" : {
      "request" : {
        "indices" : [ "logs" ],
        "body" : {
          "query" : {
            "match" : { "message": "error" }
          }
        }
      }
    }
  },
  "condition" : {
    "compare" : { "ctx.payload.hits.total.value" : { "gt" : 0 }}
  },
  "actions" : {
    "log_error" : {
      "logging" : {
        "text" : "Found {{ctx.payload.hits.total.value}} errors in the logs"
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1277.console"></div>
<h3>
<a id="log-delete"></a>Delete the Watch<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/watcher/getting-started.asciidoc">edit</a>
</h3>
<p>Since the <code class="literal">log_error_watch</code> is configured to run every 10 seconds, make sure you
delete it when you’re done experimenting. Otherwise, the noise from this sample
watch will make it hard to see what else is going on in your watch history and
log file.</p>
<p>To remove the watch, use the <a class="xref" href="watcher-api-delete-watch.html" title="Delete watch API">delete watch API</a>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">DELETE _watcher/watch/log_error_watch</pre>
</div>
<div class="console_widget" data-snippet="snippets/1278.console"></div>
<h3>
<a id="required-security-privileges"></a>Required security privileges<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/watcher/getting-started.asciidoc">edit</a>
</h3>
<p>To enable users to create and manipulate watches, assign them the <code class="literal">watcher_admin</code>
security role. Watcher admins can also view watches, watch history, and triggered
watches.</p>
<p>To allow users to view watches and the watch history, assign them the <code class="literal">watcher_user</code>
security role. Watcher users cannot create or manipulate watches; they are only
allowed to execute read-only watch operations.</p>
<h3>
<a id="next-steps"></a>Where to go next<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/watcher/getting-started.asciidoc">edit</a>
</h3>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
See <a class="xref" href="how-watcher-works.html" title="How Watcher works"><em>How Watcher works</em></a> for more information about the
anatomy of a watch and the watch lifecycle.
</li>
<li class="listitem">
See <a class="xref" href="example-watches.html" title="Example watches"><em>Example watches</em></a> for more examples of setting up
a watch.
</li>
<li class="listitem">
See the <a href="https://github.com/elastic/examples/tree/master/Alerting" class="ulink" target="_top">Example
Watches</a> in the Elastic Examples repo for additional sample watches you can use
as a starting point for building custom watches.
</li>
</ul>
</div>
</div>
<div class="navfooter">
<span class="prev">
<a href="xpack-alerting.html">« Alerting on cluster and index events</a>
</span>
<span class="next">
<a href="how-watcher-works.html">How Watcher works »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
